home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d912.lha / UUArc / UUArc.doc < prev    next >
Text File  |  1993-10-03  |  15KB  |  381 lines
  1. CONTENTS
  2. --------
  3.  
  4.                      UUARC Version 1.1 08/07/93
  5.                              J.G.BRANDON
  6.  
  7.                             PUBLIC DOMAIN
  8.  
  9.  
  10.   Introduction
  11.  
  12.   Reason For Writing The Program
  13.   Detailed Description of Program
  14.   Installation Procedure
  15.   Technical Reference Information
  16.   History
  17.   Bug Reports and Future Updates
  18.  
  19.   Acknowledgements
  20.  
  21.   Bibliography
  22.  
  23.   Quick Usage Reference
  24.  
  25.  
  26.  
  27.  
  28. INTRODUCTION
  29. ------------
  30.  
  31. UUArc is an archiving system designed to enable easy transmission of
  32. binary files/archives over communcation links only capable of using
  33. ASCII, such as Electronic Mail.  It encodes binary
  34. files into files containing only printable standard ASCII characters.
  35.  
  36. Written primarily for use with GuiArc to add UUEncoding/UUDecoding
  37. facilities to it, it takes similar command line options to other commonly
  38. used archiving programs - though if you intend to use the program only via
  39. GuiArc they will not be of much interest to you.
  40.  
  41. There is a fairly comprehensive installation script included,
  42. called 'Install' which will automatically install UUArc into your system,
  43. including adding to the ArcTypes file so that, if you have it, GuiArc
  44. be able to use UUArc and play with UUEncoded files from now on.
  45.  
  46.  
  47. If you like this program, use it a lot, and can afford to do so,
  48. contributions to a charity in the U.K. called C.I.C.R.A.
  49. would be very much appreciated.
  50.  
  51. Enjoy.  :-)
  52.  
  53.  
  54.  
  55.  
  56. REASON FOR WRITING THE PROGRAM
  57. ------------------------------
  58.  
  59. At the moment, it is more practical for me to obtain most of my
  60. software via E-Mail, which means having to UUEncode/UUDecode
  61. all the files and archives, as E-Mail can only handle ASCII.
  62.  
  63. Now that the rather fabulous GuiArc program is available, all
  64. my archiving can by done via a nice graphic user interface
  65. rather than the horrid CLI that I used to be stuck with....
  66.  
  67. almost......
  68.  
  69. BUT as I have to UUEncode/UUDecode, I was stuck having to return to
  70. the CLI to use the rather old UUE/UUD programs.  I hunted around for
  71. a UUE archiver that would interface nicely with GuiArc, but
  72. couldn't find any.  Certainly the few others that were available were
  73. restricted in thier use, and couldn't do some of the rather simple but
  74. very useful acts of deleting/listing/moving files in an archive - all
  75. functions that can be accessed by GuiArc and are generally available
  76. with other archiving/coding systems.
  77.  
  78. Hence the birth of UUArc!
  79.  
  80.  
  81.  
  82.  
  83. DETAILED DESCRIPTION OF PROGRAM
  84. -------------------------------
  85.  
  86. This program functions like most other archivers available, and has
  87. very similar command line options to them; so if you regularly use other
  88. archiver systems then using UUArc should be fairly intuitive - a brief
  89. discription of the command line options is given if you enter 'UUArc'
  90. or 'UUArc ?' at the CLI (obviously after installing the
  91. program!)
  92.  
  93. It is based on the standard UUEncode/UUDecode utilities already very
  94. commonly in use throughout various computer systems, and will read/write
  95. files compatable with these utilities (I have test all the
  96. ones I've managed to locate with UUArc); although UUArc allows you to
  97. store multiple files in an archive, is contained in one
  98. single executable file, and unlike most other versions
  99. available UUArc also has options to list, delete etc. files in an
  100. archive.
  101.  
  102. UUArc is completely compatable with GuiArc (so I hope anyway)
  103. and all the archiving commands that GuiArc expects to be available
  104. have been included.  The main reason for writing this program was to
  105. enable me to perform all file conversions/archiving/decoding
  106. that I ever required within the GuiArc program, so as to avoid
  107. requiring the use of a CLI at any point.  As things stood I had to do
  108. all my UUEncoding/UUDecoding via the CLI, which seemed rather a shame
  109. and somewhat irritating - as everything else I could do with GuiArc's
  110. very nice and very friendly graphical interface.  Included is
  111. a suitable ArcTypes file for GuiArc, to add to your current
  112. ArcTypes file if you so wish to do so, to allow GuiArc to the UUE
  113. system; this is automatically added by the installing program
  114. included.  The one incompatibility between UUArc and GuiArc is that
  115. you can only do operations on archives relating to one file or all
  116. files in an archive, i.e. extract all files, or selectively extract
  117. one file at a time.  You can't select to extract 3 out 8 files (for
  118. instance) in one go; in that case you would select each of the three
  119. files in turn and extract them individually under GuiArc, or
  120. extract all 8 of them in one go and ignore or delete the ones you aren't
  121. interested in - though this shouldn't really pose much of a problem;
  122. one generally wants to decode a whole archive or just one or two
  123. files from the archive, not half of it.
  124.  
  125.  
  126.  
  127.  
  128. INSTALLATION PROCEDURE
  129. ----------------------
  130.  
  131. Installation should be relatively easy, an installation script called
  132. 'Install' has been included which will attempt to do all the work for you.
  133. Basically, all it does is to copy the UUArc executable program
  134. from this directory into your 'C:' directory, and
  135. if you have GuiArc installed in SYS:Utilities, it
  136. will attempt to add a suitable ArcTypes file onto
  137. the end of your current ArcTypes file.  If the script fails then
  138. you can easily do the installation manually; copy 'UUArc' to your
  139. 'C:' directory, and add 'ArcType' onto the end of your 'ArcTypes' file
  140. (which would normally be in the same directory as GuiArc.)
  141.  
  142. The program ought to work on just about any Amiga computer system,
  143. (and most other machines if you re-compile the 'C' source
  144. code on them!)
  145.  
  146.  
  147.  
  148.  
  149. TECHNICAL REFERENCE INFORMATION
  150. -------------------------------
  151.  
  152. This program has been written in 'C' using North 'C' V1.3, and is
  153. coded as nicely as I knew how to, but also as nicely as North 'C' will
  154. allow; unfortunately North 'C' V1.3 is not completely ANSI 'C'
  155. compatable and doesn't seem to allow function prototyping, but other
  156. than that North 'C' is an extremely usefull 'C' package for the Amiga.
  157. Although I have been a serious programmer since I was 13, I am rather
  158. new to 'C'!
  159.  
  160. The 'C' Source Code has of course been included, and
  161. is fairly self-explanitory.
  162.  
  163. I have written the program with machine portability in mind, hid any
  164. documentation I had on my Amiga, and tried to stick to only the
  165. standard 'C' libraries.  Unfortunately there is one machine specific
  166. part of the code which relates to extracting a filename from a
  167. filename with a full path attached to it; though this section of the
  168. code (like the rest of it) has been fairly thoroughly documented, so
  169. ought to be relatively easy to change as required by even the most
  170. novice of programmers.  Having said that, although I have no
  171. experience writing 'C' code for UN*X, I just uploaded an exact copy of
  172. the source supplied onto a UN*X machine; it compiled and ran first
  173. time, successfully, without any errors at all (which rather made my
  174. day!)
  175.  
  176. Basically, the UUEncoding algorithm works by taking sets
  177. of 3 8-bit bytes from the source file, and translates them into sets of
  178. 4 ASCII characters, each ASCII character being between decimal 33
  179. ("!") and decimal 96 ("`").  Each line of UUEncoded data is proceeded
  180. by a UUEncoded number indicating the number of bytes required to be
  181. extracted from that line, is within normal line width boundaries
  182. (generally around 61 characters long) and is terminated like a
  183. normal text file line.  The start of a UUEncoded file in an archive
  184. is indicated by a line containing a 'begin' statement (in lower case)
  185. followed by the file mode protection bits (3 digit octal number -
  186. ignored in this version as it would make the code rather system
  187. specific) followed by the name of the file.  The end of a file is
  188. indicated by a line containing an 'end' statement (again in lower
  189. case.)  Optionally a 'size' statement followed by the size of the
  190. file (decoded) in bytes can be included in a line after an 'end'
  191. statement line.
  192.  
  193. Checksums have been used in UUEncoding algorithm - outputed in
  194. UUEncoded form after the data bytes at the end of the line; although
  195. checksum output can be stopped by removing the compiler pre-processor
  196. define called 'ADDCHECK'.  The UUDecoding algorithm will check
  197. checksums digits if they have been included, but does not require
  198. them.  The 'size' statement is included in UUEncoding, but is optional
  199. for decoding - if it is there then it will be checked, but again the
  200. decoding algorithm doesn't actually require it to be there.
  201.  
  202. The program makes its best attempt to work out if an archive is corrupt
  203. by checking that all lines containing UUEncoded data are of the
  204. right length, and all UUEncoded characters are between the
  205. right limits, and checks any checksums (if present.)  If a UUEncoded line
  206. appears to be corrupt then that line is ignored and an error is
  207. displayed on the screen; though the rest of that file will be still be
  208. processed - this means that you ought to be able to give UUArc a mailbox
  209. full of UUEncoded files, even if each UUEncoded file has been split up
  210. into many seperate e-mails, as long as all the lines of the UUEncoded
  211. files are in the mailbox and in the right order the mailbox file could
  212. be processed by UUArc just as any other UUEncoded archive would be;
  213. UUArc would spew out a few errors about encountering bad lines - but
  214. these lines would presumably be the 'human' textual parts of the E-Mail
  215. and have nothing to do with the UUEncoded file; UUArc would just ignore
  216. such lines and only extract from the definitely UUEncoded lines!  Infact,
  217. just to test this was completely true, I stuck my current 100Kbytes of
  218. mailbox right into the middle of a UUEncoded archive (including all the
  219. e-mail headers etc. of course) 8-O - UUArc successfull managed to decode the
  220. files in the archive without any difficulty still.  8-)
  221.  
  222. I am neither an Amiga 'Guru' (though I've owned one back since the
  223. days the Fish disks were only into double digits) or an amazing
  224. 'C' hack; so the code is most certainly not the fastest of the
  225. UUEncoder/UUDecoder around, but hopefully it makes up for this in its
  226. completeness and portability.  If you find any bugs or have any
  227. suggestions, please do get in contact with me - I'm an
  228. electronics/computing student and am currently spending time trying to
  229. get up to date with programming langauges; I sort-of avoided 'C' for
  230. quite a while and am now paying my penance by spending many hours
  231. practising writing 'C' code, particularly portable 'C', so any comments
  232. you have on my programming style would actually be greatly appreciated.
  233.  
  234. Enjoy.  :-)
  235.  
  236.  
  237.  
  238.  
  239. HISTORY
  240. -------
  241.  
  242. V1.1 - 08/07/93
  243.   Recognises more signals to abort.
  244.  
  245. V1.0 - 07/07/93
  246.   First version completed and released.
  247.  
  248.  
  249.  
  250.  
  251. BUG REPORTS AND FUTURE UPDATES
  252. ------------------------------
  253.  
  254. Contact over internet would not be to easy at the moment;
  255. I'm likely to go through quite a few more e-mail address changes as
  256. time goes on, so its best to stick with snail mail for now-
  257.  
  258.   Julie Brandon,
  259.   1, Olivers Mill,
  260.   New Ash Green,
  261.   Longfield,
  262.   Kent DA3 8RE,
  263.   UNITED KINGDOM.
  264.  
  265.  
  266.  
  267. ACKNOWLEDGEMENTS
  268. ----------------
  269.  
  270. I would like to give great thanks to all those who have contributed to
  271. the Public Domain utilities/languages for the Commodore Amiga;
  272. especially the writers of North 'C', A68k, and Blink, and
  273. of course not forgetting Fred Fish for his work in putting
  274. together a renowned reliable source for this software; specifically
  275. because I haven't ever had nearly enough money to buy a 'C'
  276. compiler for my Amiga, infact since I bought
  277. my Amiga back in the late 80's I haven't been able to afford to
  278. purchase any programming languages or any Amiga documentation!
  279. (Other than the 'The Kickstart Guide To The Amiga' and very recently
  280. Kernighan & Ritchie's 2nd Edition of 'The C Programming Language.'
  281.  
  282. I owe all the 'usefulness' I get out of my Amiga is due to the fantastic high
  283. quality utilities/langauges available on Public Domain, especially via
  284. the Fish Disk collections.  Without the Public Domain versions of
  285. many languages available for the Amiga, the grades I got during my first
  286. and second year at University would have probably been very
  287. considerably lower, and most certainly would have ment many many
  288. dreary nights stuck in terminal rooms all night fighting for use of a
  289. computer and printer.  In my second year 10 miles away from my place
  290. of residence:  away from piece, tranquility, a nice graphics user
  291. interface, cups of tea, Marmite sandwiches, decent music, a nice
  292. bath/shower, and a bed immediately on completion of any programming work.
  293.  
  294. If I knew the origins of the UUEncoding/UUDecoding algorithms, then I'd
  295. have acknowledged the programmer here!
  296.  
  297.  
  298.  
  299.  
  300. BIBLIOGRAPHY
  301. ------------
  302.  
  303. THE 'C' PROGRAMMING LANGUAGE - 2nd Edition
  304.     Brian W. Kernighan
  305.     Dennis M. Ritchie
  306.     ISBN 0-13-110362-8
  307.     Prentice Hall Software Series
  308.  
  309. Recommended reading for anyone wishing to pursue learning the 'C'
  310. language, with a good reference section also for those well
  311. experienced with programming other langauges.  Not recommended for
  312. novice programmers.
  313.  
  314.  
  315. THE 'KICKSTART' GUIDE TO THE AMIGA
  316.     ISBN 0-9512921-0-2
  317.     Ariadne Software Ltd,
  318.     273 Kensal Road, London W10 5DB, ENGLAND.
  319.  
  320. The version I have came out just when Kickstart 1.2
  321. was released, and therefore is rather out of date.  If this is still in
  322. print and if an up-to-date version of it is available, definitely
  323. the 'paupers' replacement to having all the official books.
  324.  
  325.  
  326.  
  327.  
  328. QUICK USAGE REFERENCE
  329. ---------------------
  330.  
  331. Usage with CLI only.  No graphical user interface is
  332. available by default; that is what GuiArc is for!
  333.  
  334.  
  335. UUArc Version 1.1 by Miss J.G.Brandon Jly 08 1993.
  336.  
  337.  
  338. USAGE:  UUArc -<command>[p] <archive> [<filename>]
  339.  
  340. Where <command> is one of-
  341.         l = List contents of <archive>.
  342.         t = Test contents of <archive>.
  343.         a = Add <filename> to <archive>.
  344.         m = Move <filename> to <archive>.
  345.         x = Extract <filename> from <archive>.
  346.             (All files if <filename> is missing.)
  347.         d = Delete <filename> from <archive>.
  348.             (All files if <filename> is missing.)
  349.  
  350. If included after the archiver command, the 'p' option
  351. specifies full path names to be considered; otherwise path
  352. names will be ignored by default.
  353.  
  354. If applicable, <archive> must include the '.uue' extension.
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361. C.I.C.R.A.
  362. ----------
  363.  
  364. If you can afford to do so, donations to the following U.K. charity,
  365. or your countries equivalent, would be very very much appreciated:-
  366.  
  367.  
  368.   CICRA,
  369.   Parkgate House,
  370.   356 West Barnes Lane,
  371.   Motspur Park,
  372.   Surrey,
  373.   KT3 6NB.
  374.   UNITED KINGDOM.
  375.  
  376.  
  377. I can't afford to pay them back in monetary means much for all the
  378. help they gave me and my family when I was younger, so the next
  379. best thing I can think of doing is to donate my computer programs
  380. for them. :-)
  381.